//===============================================================================
// Microsoft patterns & practices
// Mobile Client Software Factory - July 2006
//===============================================================================
// Copyright  Microsoft Corporation.  All rights reserved.
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY
// OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
// LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
// FITNESS FOR A PARTICULAR PURPOSE.
//===============================================================================
// The example companies, organizations, products, domain names,
// e-mail addresses, logos, people, places, and events depicted
// herein are fictitious.  No association with any real company,
// organization, product, domain name, email address, logo, person,
// places, or events is intended or should be inferred.
//===============================================================================

using System;
using System.Collections.Generic;
using System.Text;
using System.CodeDom.Compiler;
using System.CodeDom;

namespace Microsoft.Practices.ObjectBuilder.ObGen
{
	/// <summary>
	/// Interface implemented by generators that inject policies via code generation.
	/// </summary>
	public interface IPolicyGenerator
	{
		/// <summary>
		/// Assembly references required to compile the method snippet generated by this generator. 
		/// This property is called after the <see cref="GenerateStatements"/> method has been run and 
		/// only if a non-empty collection of statements has been returned.
		/// </summary>
		string[] AssemblyReferences { get; }

		/// <summary>
		/// Namespace imports required at the class level to compile the method snippet generated by this generator.
		/// This property is called after the <see cref="GenerateStatements"/> method has been run and 
		/// only if a non-empty collection of statements has been returned.
		/// </summary>
		string[] NamespaceImports { get; }

		/// <summary>
		/// The code statements must be statements that run in a method that (by default, 
		/// as defined by the <see cref="PolicyProviderGenerator"/>) provides a 
		/// a single variable declaration named <c>policies</c>, and a protected <c>Policies</c> 
		/// property, that can be used by the generated code to inject policies. Also, the 
		/// statements live inside the implementation of the <see cref="IPolicyProvider.GetPolicies"/> 
		/// method, so the incoming parameters are available too.
		/// </summary>
		/// <param name="typeToProcess">The type to inject the policies for.</param>
		/// <param name="generatedType">The declaration being generated, that will contain the method with the 
		/// statements returned.</param>
		/// <param name="namingContext">Context that can be used to acquire variable and member names and avoid 
		/// naming collisions with other policy generators.</param>
		/// <returns>A set of statements to inject in the strongly-typed <see cref="IPolicyProvider"/> to generate.</returns>
		/// <remarks>
		/// If the generator determines that no code is needed, it can return <see langword="null" /> or an empty collection. 
		/// <para>
		/// A generator that prefers to generate code using a templating mechanism, or hardcoded strings, can use the 
		/// <see cref="CodeSnippetStatement"/> to do so. The code must be in the same language supported by the 
		/// <see cref="CodeDomProvider"/> specified for the generator.
		/// </para>
		/// </remarks>
		CodeStatementCollection GenerateStatements(Type typeToProcess, CodeTypeDeclaration generatedType, NamingContext namingContext);
	}
}
